Skip to content

Layer API: let developers register their own layer types (EPIC #2290) - #2345

Merged
KMchaudhary merged 32 commits into
developfrom
feature/layer-api
Nov 11, 2026
Merged

KMchaudhary merged 32 commits into
developfrom
feature/layer-api

Conversation

@KMchaudhary

@KMchaudhary KMchaudhary commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #2290 · #2291 #2292 #2293 #2294 #2295 #2296 #2297

Merges the Layer API EPIC branch feature/layer-api into develop. Every part was reviewed and merged into that branch through its own PR (listed below). This PR brings them to develop as one unit, after merging the latest develop into the branch.

What the Layer API gives developers

Developers build a custom layer type for GoDAM's video player and godam/image block the way they build a Gutenberg block. Each layer type is a folder with a layer.json, a PHP file, and editor and view scripts:

my-layer/
├── layer.json   name, title, supports.media, attributes, editorScript, viewScript, style
├── my-layer.php godam_register_layer_type( __DIR__ . '/layer.json', [ 'render_callback' => … ] )
├── editor.js    window.godam.layers.registerLayerType( name, { edit, create, … } )
├── edit.js      the settings panel (useLayerAttributes() from window.godam.layerEditor)
└── view.js      window.godam.layers.registerLayerRuntime( name, { mount, validate, … } )
Area What changed
Editor A layer type registry (registerLayerType()) and window.godam.layerEditor (panel components and hooks), so add-ons no longer reach into GoDAM's Redux store. Form plugins are variations of the Form layer.
Front end One runtime runs video and image layers (registerLayerRuntime()), with mount and validate hooks, player events, shared controllers and error isolation. Layers whose script loads late (deferred or delayed JS) still mount.
PHP godam_register_layer_type() on godam_init, with render_callback, is_available, should_render and variations. The player template renders every layer through its type's callback. Layers are cleaned on save against their layer.json attributes.
Loading A type's viewScript and style load only on pages that show that layer type (and in the block editor and page-builder previews). The image layers script went from 33 KB to 16.5 KB.
Core layers CTA, Form, Poll, Hotspot and Ad live in assets/src/layers/<type>/ like Gutenberg's core blocks, built to assets/build/layers/<type>/.
layer.json style, viewStyle and editorStyle, plus PHP translation of title, description and variation titles, as block.json has.
Old add-on hooks godam_video_editor_layer_options, godam_video_editor_layer_components, godam_player_render_layer, window.godamLayerRegistry, window.godamLayerComponents, window.godamLayerCreators and window.godamVideoEditorActions keep working behind compatibility shims and log a deprecation notice.
Docs docs/layer-api.md, the developer guide: quick start, every layer.json key, PHP/editor/front-end APIs, form providers, migration from the old hooks, troubleshooting.

Parts, already merged into feature/layer-api

  1. test(layers): Layer API contract tests and RFC draft #2302: S1, contract tests and RFC
  2. ci: run unit tests on PRs into the Layer API base branch #2307: CI on PRs into the EPIC branch (the trigger is removed again in this PR)
  3. feat(layers): Layer API editor registry #2306: S2, editor registry
  4. feat(layers): register form providers as Form layer variations (S3) #2319: S3, form providers as Form layer variations
  5. feat(layers): run video and image layers on one front-end runtime (S4) #2321: S4, one front-end runtime for video and image layers
  6. feat(layers): register layer types in PHP and render them through callbacks (S5, part 1) #2322: S5 part 1, PHP registry and render callbacks
  7. feat(layers): clean layers on save, and load layer scripts only where used (S5, part 2) #2324: S5 part 2, cleaning on save, layer scripts only where used
  8. feat(layers): deprecate the old add-on layer hooks behind shims (S6) #2325: S6, deprecation shims for the old add-on hooks
  9. docs(layers): add the Layer API developer guide (S7) #2327: S7, developer guide
  10. refactor(layers): give each core layer type its own folder, built like core blocks #2328: core layers in their own folders, built like core blocks
  11. Layer API: stylesheets and translations in layer.json, like block.json #2331: stylesheets and translations in layer.json

Merging develop in (d1b377c)

develop had 30 newer commits. Five files conflicted, and two develop fixes had to be carried into code the EPIC moved:

  • Validate colours, layer CSS, Gravity Forms theme and embed HTML in player output #2246, colours and Gravity Forms theme in player output. The template's per-layer markup is now in the render callbacks, so Core_Layer_Types::container() prints only a plain background colour (rtgodam_sanitize_css_color(), default #FFFFFFB3, none for hotspots). The Gravity Forms provider uses rtgodam_get_gravityform_layer_shortcode(). New tests cover both.
  • Only use http, https and mailto links, and sanitise preview markup #2250, safe links and preview markup in the panels. The CTA, Hotspot and Poll panels moved to assets/src/layers/<type>/edit.js and keep getSafeLinkUrl() / sanitizePreviewMarkup(). Only use http, https and mailto links, and sanitise preview markup #2250's panel tests moved beside them.
  • CI: keeps develop's workflow_call and removes the temporary feature/layer-api triggers.
  • Tests:
    • HotspotLinkSanitizeTest loads the layer registry.
    • Two test stubs stopped depending on load order: delete_post_meta() in media-visibility-functions.php, and do_shortcode() / sanitize_key() in layer-registry.php.
  • Lint: two lint errors develop already had (a doc comment in storage.js, a blank line in analytics-unavailable.scss) are fixed so the commit passes the lint hooks.

Compatibility

  • Saved layers keep their shape; nothing is migrated. Layer markup on the page is identical before and after (compared on four videos and the image block).
  • Public player API (GoDAMAPI / player.layersManager: replay, dismissNativeLayer, getAllNativeLayers, createLayer) is unchanged.
  • GoDAM for Woo: the current release keeps working through the shims. Its move to the Layer API is rtCamp/godam-for-woo#251, which must ship after the GoDAM release that contains this PR.
  • Out of scope: GoDAM Central. It can adopt the API later.

Testing

  • PHPUnit: 1,434 tests pass.
  • Jest: 1,243 tests in 88 suites pass.
  • Builds: build:js and build:blocks succeed.
  • Lint: the pre-commit ESLint, Stylelint, PHPCS and package.json checks pass.
  • Live check on the whole stack (before the develop merge), posted on the EPIC with 13 screenshots:
    • CTA, the form plugins, WP-Polls and hotspot layers on video
    • image hotspots
    • layers inside the gallery modal
    • every editor panel, the Add layer picker, and saving (layer data byte-identical after save)
    • the player API
CTA layer pauses the video Hotspot tooltip
CTA layer Hotspot tooltip
Gallery modal: WPForms layer Editor: Add layer → Form picker
Gallery modal WPForms Form picker

Not verified locally:

  • Ad playback: Chrome blocks Google's IMA from loading a localhost ad tag. The VMAP is correct, and class-ads.php is unchanged.
  • Woo product hotspots on the front end: the local site has no GoDAM API key.

Version numbers

main is at 2.7.0 (released) and develop at 2.8.0, so this ships in 2.8.0. The deprecations therefore read "since 2.8.0, removed in 2.10.0" (d0fe1a3), two minor releases later as the code states. New functions use @since n.e.x.t for the release script.

🤖 Generated with Claude Code

KMchaudhary and others added 27 commits November 3, 2026 15:39
Pin down how layers behave today, so the Layer API refactor (#2290) can
move core layer types onto a registry and prove nothing changed:

- Editor: the data each core type starts with, the add-on menu and
  creator path, media-type gating, settings-panel selection, and the
  window globals add-ons use.
- Player: which manager gets each layer, add-on managers, validation,
  and the shared front-end registry and queue.
- Image block: which saved layers reach the browser, and how the image
  renderer draws hotspot and woo layers.

Tests marked "current behaviour" pin what the refactor intends to
change on purpose.

Also add the RFC draft (docs/rfcs/layer-api.md) with the audit of every
reader of saved layers, and keep /docs/ out of the release package.

Refs #2291

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Layer API EPIC covers the plugin only. Central adopts the API from
the plugin once it lands, so drop the open question about Central's
player and say so in the RFC's scope.

Refs #2291

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every Layer API PR (#2290) targets feature/layer-api, which neither the
JS nor the PHP unit-test workflow listed, so those PRs got no unit
tests. Remove the entries once feature/layer-api is merged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
test(layers): Layer API contract tests and RFC draft
Accepted as written. D1 now separates the keys GoDAM manages (id,
type, name, displayTime) from shared keys a layer type may give its
own default (duration, allow_skip, custom_css, trigger, watchDepth),
which core types already rely on.

Refs #2291

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit afa0664)
Add a layer type registry the editor and add-ons share (#2292):

- `godam-layers` script (`window.godam.layers`, `@godam/layers`): a
  `godam/layers` wp-data store with registerLayerType(),
  unregisterLayerType() and the `godam.layers.registerLayerType` filter.
- Core layer types (CTA, Hotspot, Form, Poll, Ad) register through it,
  with metadata in assets/src/layers/<type>/layer.json. Form plugins are
  variations of the Form type; Form's save check is its validate().
- The add menu, settings panel, layer list, header, timeline, save
  validation and image gating read the registry. Removes
  utils/layerTypes.js and the allowedLayerTypes allowlist.
- Add-on types from the old hooks (godam_video_editor_layer_options and
  friends) are bridged into the registry, so godam-for-woo is unchanged.
- `window.godam.layerEditor` (`godam-layer-editor` handle) gives add-on
  panels useLayer() / useLayerAttributes() and the shared controls.
- A saved layer whose type isn't registered stays in the list with a
  warning and opens a "needs an add-on" notice instead of the CTA
  editor (RFC D2).

Timeline chips for Marketo and HubSpot form layers now name the form
plugin; they showed "Gravity Forms" before.

Refs #2292

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each of the 12 form plugins is now one registerLayerVariation( 'form', … )
call carrying its title, icon, availability, panel, form-ID field and
settings URL, replacing the FormLayerComponentType table. Add-ons can
register their own provider; one without a panel supplies getForms() and
getFormHtml( id ) and gets a shared FormProviderPanel. A form layer whose
provider isn't registered shows a notice instead of an error.

Adds registerLayerVariation, unregisterLayerVariation,
getLayerVariationByName and getUnavailableReason to the registry. A
variation registered before its type is kept and added later.

Editor only; the player and PHP parts move to #2294 and #2295.

Refs #2293

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds the Layer API front-end runtime (#2294): registerLayerRuntime( name,
{ validate, mount, supports, usesIconFont, variations } ) on
window.godam.layers, plus a layer host that mounts each saved layer and
forwards player events (onReady, onTimeUpdate, onPause, onEnded, onPlay,
onResize, onFullscreenChange, onReplay, destroy) to the handlers mount()
returns. ctx.api gives pause, play, seek, show, hide, track and
isSuppressed.

- LayersManager and render-image-frame both mount through the host and no
  longer branch on layer type names.
- CTA, Form, Poll and Hotspot are core runtimes; CTA, Form and Poll share
  one FormLayerManager, which now takes a per-type behaviour.
- The 12 form providers register their front-end part as Form variations:
  availability, "submitted" detection and analytics label. This replaces
  LayerValidator, FORM_TYPES and hasConfirmationMessage.
- Hover-preview suppression covers every runtime, including layers from
  GoDAMAPI.createLayer() (RFC D5), which now mount on the same host.
- window.godamLayerRegistry is a shim over the new registry, and still
  drains window.godamLayerRegistryQueue. The window store workaround is
  gone, and godam-for-woo's manager runs unchanged on video and images.
- An unregistered type is logged once and skipped (RFC D2).

Refs #2294

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lbacks

Adds the PHP half of the Layer API (#2295):

- godam_register_layer_type( $path_or_metadata, $args ) on a new godam_init
  action, reading layer.json, with the godam_layer_type_metadata filter, and
  godam_register_layer_variation() / godam_get_layer_type() /
  godam_render_layer().
- render_callback( $layer, $instance_id, $context ) prints a layer's
  container. The core CTA, Form, Poll and Hotspot types carry the markup the
  player template printed inline, so godam-player.php loops over
  godam_render_layer() with no layer type names. Add-on output goes through
  wp_kses_post() unless the type sets supports.rawHtml (RFC D3).
- The 12 form providers register their PHP part as Form variations: render
  callback and is_available. godamPluginDependencies is now built from each
  type's and provider's is_available.
- godam/image sends the layers whose type supports images and has something
  to draw (should_render), instead of hard-coding hotspot and woo.
- The ad tag is requested for layers whose type supports adTag. Typeless
  layers no longer warn there.
- A type with no PHP registration still renders through the old
  godam_player_render_layer action, and the Woo layer is registered as a
  legacy type until #2296 moves godam-for-woo over.

Sanitizing on save, localizing PHP metadata to the editor and per-page
script loading follow in a second PR for #2295.

Refs #2295

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… used

Second part of #2295:

- Saving rtgodam_meta cleans each layer against its type's declared
  attributes (RFC D3, Layer_Sanitizer). Add-on types are strict: declared
  values are sanitized by type and format (plain, html, url, color), a wrong
  type falls back to the default, and undeclared keys are dropped. Core
  types stay lenient (keep_undeclared_attributes) until their layer.json
  lists every attribute: they keep undeclared keys, mismatched values and
  HTML (escaped at render) as saved. Unregistered types are kept unchanged.
- Attributes marked "private": true are left out of the player's
  data-options and the image block's layer data.
- layer.json editorScript and viewScript ("file:./…" or a handle) are
  registered as scripts. Editor scripts load in the video editor; a view
  script loads only when a layer of its type renders. A new
  godam-layer-runtime script handle exposes the front-end runtime registry
  for add-on view scripts.
- The video editor gets each PHP-registered type's metadata and
  availability (godamVideoEditorConfig.layerTypes / layerAvailability), and
  registerLayerType() fills in that metadata, so an add-on can register by
  name. The videoData *Active form flags now come from the registry.

Refs #2295

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part of #2296. The hooks the Layer API replaces keep working, fed into the
registry, and log a deprecation notice. They are deprecated since 2.7.0 and
removed in 2.9.0:

- PHP: godam_video_editor_layer_options and
  godam_video_editor_layer_components (apply_filters_deprecated), and
  godam_player_render_layer (do_action_deprecated).
- JS: window.godamLayerComponents, window.godamLayerCreators,
  window.godamVideoEditorActions and
  window.godamLayerRegistry.registerLayerType(), each logging one console
  notice per page.

So godam-for-woo can register its own `woo` type:

- The legacy `woo` registration runs late on godam_init, after add-ons.
- The editor accepts the `woo` name without a namespace, because saved
  layers use it.
- Panels get a useMediaType() hook.
- The analytics page reads add-on icons from layer types registered through
  the API.

Refs #2296

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs/layer-api.md, for add-on developers (#2297):

- how a layer type fits together
- a quick-start countdown layer plugin
- the layer.json reference
- the PHP, editor and front-end runtime references
- form providers
- the saved data shape and analytics
- moving from the deprecated hooks
- troubleshooting

Refs #2297

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e core blocks

GoDAM's core layer types now follow the structure an add-on layer type
uses, the way Gutenberg's block-library holds each core block:

  assets/src/layers/<type>/
    layer.json   metadata, with "viewScript": "file:./view.js"
    <type>.php   render callback + godam_register_layer_type()
    editor.js    registerLayerType() settings
    edit.js      the settings panel (moved from pages/video-editor)
    view.js      registerLayerRuntime() (moved from godam-player/layers)

A new `layers` webpack config builds each view.js (with its
view.asset.php) into assets/build/layers/<type>/ and copies layer.json and
the PHP beside it. Core_Layer_Types loads each type from the build, falling
back to the source when the plugin isn't built.

- View scripts load only on pages that show that layer type (Gutenberg
  viewScript behaviour), instead of being bundled into the player and image
  scripts. The image script drops from 33 KB to 16.5 KB.
- The block editor and the Elementor and WPBakery editors, which draw
  layers without the page rendering them, enqueue the view scripts up front.
- The shared FormLayerManager behind CTA, Form and Poll stays in the
  player bundle. The views only add their layers to it.
- whenLayerRuntime() lets a player or image mount a layer whose view script
  loads after it started (deferred or delayed JS).
- The registry only registers built file: scripts (with an *.asset.php),
  sets their translations, and prefixes core handles with godam-layer-.
- assets/src/layers is left out of the release; it ships from
  assets/build/layers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PHPCS (WordPressVIPMinimum) flags both includes. Each path is built by the
plugin: the core loader from its layer folder and fixed type list, the
registry from a registered layer.json's built *.asset.php.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…k.json

- Support `style`, `viewStyle` and `editorStyle` (a handle or `file:./x.css`,
  string or array). `file:` styles register with their path and `-rtl.css`
  twin; `style` + `viewStyle` load wherever view scripts do, `style` +
  `editorStyle` with the editor scripts, and image types' view styles reach
  the block editor canvas through `enqueue_block_assets`.
- Translate `title`, `description` and variation strings with the type's
  `textdomain` and gettext context, as core does for block.json, falling back
  to the same string without a context. The editor prefers these over the
  untranslated layer.json strings its script imports.
- Point script translations at GoDAM's languages folder only for GoDAM's own
  layer.json files; add-ons use WordPress's default lookup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tor canvas

The block editor collects its canvas styles before `admin_enqueue_scripts`,
where `godam-player-wrapper-style` was registered. `godam-player-style`
(tied to godam/image with wp_enqueue_block_style) had an unregistered
dependency there, so WordPress dropped it, and with it every stylesheet that
depends on it. The Woo product-hotspot popup rendered unstyled in the
godam/image preview: its product image filled the canvas.

Register both handles on `init` through GoDAM_Player::register_player_styles().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ci: run unit tests on PRs into the Layer API base branch
feat(layers): register form providers as Form layer variations (S3)
feat(layers): run video and image layers on one front-end runtime (S4)
feat(layers): register layer types in PHP and render them through callbacks (S5, part 1)
feat(layers): clean layers on save, and load layer scripts only where used (S5, part 2)
feat(layers): deprecate the old add-on layer hooks behind shims (S6)
docs(layers): add the Layer API developer guide (S7)
refactor(layers): give each core layer type its own folder, built like core blocks
Layer API: stylesheets and translations in layer.json, like block.json
Brings the Layer API branch up to date with develop before it merges back.

Conflicts, and develop changes carried into the Layer API's new files:
- inc/templates/godam-player.php: layers render through their type's
  render_callback now, so the template keeps the Layer API side. develop's
  #2246 checks move into the callbacks: Core_Layer_Types::container() prints
  only a plain background colour (rtgodam_sanitize_css_color(), default
  #FFFFFFB3, none for hotspots), and the Gravity Forms provider builds its
  shortcode with rtgodam_get_gravityform_layer_shortcode(), so the theme is a slug.
- assets/src/layers/{cta,hotspot,poll}/edit.js (the panels moved out of
  pages/video-editor/components/layers): keep the new import paths and add
  #2250's getSafeLinkUrl / sanitizePreviewMarkup imports. #2250's panel tests
  move beside them as edit.test.js.
- PHP and JS unit test workflows: keep develop's workflow_call and drop the
  feature/layer-api trigger, which was only for the EPIC's PRs.

Tests:
- HotspotLinkSanitizeTest loads the layer registry, which the image block now
  filters its layers through.
- New tests cover the background colour and Gravity Forms theme in the render
  callbacks.
- The layer registry stub defines sanitize_key() and returns content from
  do_shortcode(); the CTA test registers a shortcode, because the bootstrap's
  do_shortcode() returns '' while none is registered.
- media-visibility-functions.php's delete_post_meta() removes the value like
  the other stubs, so MediaLibraryAttachmentAccessTest passes whichever loads first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 6, 2026 06:16

@rtBot rtBot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code analysis identified issues

action-phpcs-code-review has identified potential problems in this pull request during automated scanning. We recommend reviewing the issues noted and that they are resolved.

phpcs scanning turned up:

⚠️ 1 warning


Powered by rtCamp's GitHub Actions Library

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

🔍 WordPress Plugin Check Report

⚠️ Status: Passed with warnings

📊 Report

🎯 Total Issues ❌ Errors ⚠️ Warnings
13 0 13

⚠️ Warnings (13)

📁 readme.txt (1 warning)
📍 Line 🔖 Check 💬 Message
0 mismatched_plugin_name Plugin name "GoDAM - Video Hosting for LMS & Online Courses" is different from the name declared in plugin header "GoDAM".
📁 assets/build/pages/video-editor.min.js (1 warning)
📍 Line 🔖 Check 💬 Message
2 react_removed_api This file calls "ReactDOM.findDOMNode", which was removed in React 19 and stops working once WordPress upgrades React. Use a ref on the element instead.
📁 assets/build/css/main.css (1 warning)
📍 Line 🔖 Check 💬 Message
0 EnqueuedStylesScope This style is being loaded in all contexts.
📁 assets/src/libs/analytics.min.js (5 warnings)
📍 Line 🔖 Check 💬 Message
0 EnqueuedScriptsScope This script is being loaded in all frontend contexts.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880 (with handle analytics-library) is loaded in the footer. Consider a defer or async script loading strategy instead.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880/2026/11/11/hello-world/ (with handle analytics-library) is loaded in the footer. Consider a defer or async script loading strategy instead.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880/sample-page/ (with handle analytics-library) is loaded in the footer. Consider a defer or async script loading strategy instead.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880/demo-attachment-post/ (with handle analytics-library) is loaded in the footer. Consider a defer or async script loading strategy instead.
📁 assets/build/js/main.min.js (5 warnings)
📍 Line 🔖 Check 💬 Message
0 EnqueuedScriptsScope This script is being loaded in all frontend contexts.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880 (with handle rtgodam-script) is loaded in the footer. Consider a defer or async script loading strategy instead.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880/2026/11/11/hello-world/ (with handle rtgodam-script) is loaded in the footer. Consider a defer or async script loading strategy instead.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880/sample-page/ (with handle rtgodam-script) is loaded in the footer. Consider a defer or async script loading strategy instead.
0 NonBlockingScripts.NoStrategy This script on http://localhost:8880/demo-attachment-post/ (with handle rtgodam-script) is loaded in the footer. Consider a defer or async script loading strategy instead.

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Missing form providers can block unrelated attachment edits, while delayed view scripts can prevent saved forms from mounting and duplicate hotspot markers.

3 open issues
What changed in this PR

Introduces an extensible Layer API for GoDAM’s video player and image block, enabling custom layer types while preserving compatibility with legacy add-on hooks.

Changes:

  • Adds editor registries, public panel hooks, form-provider variations, and a shared front-end runtime.
  • Moves core layers into metadata-driven modules with PHP registration and rendering callbacks.
  • Adds schema-based save sanitization, conditional asset loading, compatibility shims, and supporting tests.

This pull request requires changes.

The following issues remain unresolved:

  • Critical — assets/src/layers/form/editor.js:39: Missing form-provider registrations cause validation to block saving the entire attachment. Validate required IDs only for registered providers and preserve missing-provider layers unchanged.
  • Moderate — assets/src/js/godam-layers/utils.js:37: Reference equality prevents object- and array-valued variation attributes from matching after creation or loading. Use structural comparison in both editor and runtime variation resolution.
  • Moderate — assets/src/layers/form/view.js:62: Delayed script loading publishes the Form runtime before its providers, permanently rejecting waiting form layers. Register providers before publishing the runtime.
  • Moderate — assets/src/layers/hotspot/view.js:91: Delayed mounting of multiple image hotspot layers duplicates markers and breaks index-based repositioning. Clear existing markers before rebuilding the merged set.
  • Moderate — assets/src/layers/hotspot/view.js:89: Image hotspots omit parent and per-point visibility events, leaving interaction analytics without impression denominators. Emit visibility events when drawing hotspots.
  • Moderate — pages/video-editor/components/forms/FormProviderPanel.js:71: Preview fetching still runs for unavailable providers. Gate it on isActive and include availability in the effect dependencies to prevent stale UI updates.
File Description
webpack.config.js Builds registries and per-type layer assets.
tests/​stubs/​script-functions.php Records script translations and stylesheet operations.
tests/​stubs/​media-visibility-functions.php Aligns metadata deletion behavior.
tests/​stubs/​i18n.php Adds contextual translation stubs.
tests/​stubs/​block-render-functions.php Supports standalone block-rendering tests.
tests/​php/​HotspotLinkSanitizeTest.php Initializes core layer registrations for image tests.
tests/​js/​register-core-layer-views.js Registers core runtimes for tests.
tests/​js/​mock-form-provider-panels.js Mocks form-provider panels.
tests/​js/​layer-contract-globals.js Seeds compatibility-test globals.
tests/​fixtures/​layers/​built-core/​view.js Supplies a built view-script fixture.
tests/​fixtures/​layers/​built-core/​view.asset.php Supplies built-script dependency metadata.
tests/​fixtures/​layers/​built-core/​layer.json Defines built-layer fixture metadata.
tests/​fixtures/​layers/​acme-countdown/​layer.json Exercises add-on metadata, assets, and private attributes.
tests/​fixtures/​layers/​acme-countdown/​build/​view.js Supplies an add-on runtime fixture.
tests/​fixtures/​layers/​acme-countdown/​build/​view.css Supplies a view-style fixture.
tests/​fixtures/​layers/​acme-countdown/​build/​view.asset.php Supplies runtime dependency metadata.
tests/​fixtures/​layers/​acme-countdown/​build/​style.css Supplies a shared-style fixture.
tests/​fixtures/​layers/​acme-countdown/​build/​style-rtl.css Exercises RTL stylesheet registration.
tests/​fixtures/​layers/​acme-countdown/​build/​editor.js Supplies an editor-script fixture.
tests/​fixtures/​layers/​acme-countdown/​build/​editor.css Supplies an editor-style fixture.
tests/​fixtures/​layers/​acme-countdown/​build/​editor.asset.php Supplies editor dependency metadata.
pages/​video-editor/​VideoEditor.js Delegates save validation to registered types.
pages/​video-editor/​utils/​layerTypes.js Removes duplicated editor type metadata.
pages/​video-editor/​utils/​formUtils.js Resolves provider IDs and settings URLs.
pages/​video-editor/​redux/​slice/​videoSlice.js Removes layer-type allowlist state.
pages/​video-editor/​layers/​legacy.js Bridges legacy editor registrations.
pages/​video-editor/​layers/​index.js Coordinates core and legacy editor registration.
pages/​video-editor/​layers/​hooks.js Exposes stable layer-editing hooks.
pages/​video-editor/​index.test.js Tests public editor globals and compatibility.
pages/​video-editor/​index.js Publishes editor APIs and compatibility globals.
pages/​video-editor/​config/​mediaCapabilities.js Defers layer support to registered metadata.
pages/​video-editor/​components/​timeline/​Timeline.test.js Tests registry-driven timeline markers.
pages/​video-editor/​components/​layers/​UnregisteredLayerNotice.js Displays unavailable-type notices and recovery actions.
pages/​video-editor/​components/​layers/​LayersHeader.js Resolves registered type and variation labels.
pages/​video-editor/​components/​layers/​Layer.js Selects registered panels or missing-type notices.
pages/​video-editor/​components/​forms/​FormProviderPanel.test.js Tests shared provider-panel behavior.
pages/​video-editor/​components/​forms/​FormProviderPanel.js Adds provider-driven selection and previews.
pages/​video-editor/​components/​forms/​fetchForms.js Gates form queries through provider availability.
pages/​video-editor/​_layers.scss Styles error and missing-type notices.
pages/​shared/​analytics-unavailable.scss Adds lint-required comment spacing.
package.json Declares registry and build dependencies.
package-lock.json Synchronizes dependency declarations.
jest.config.js Maps editor registry imports to source.
inc/​helpers/​layer-functions.php Exposes public PHP registration and rendering helpers.
inc/​helpers/​autoloader.php Supports layer-class autoloading.
inc/​classes/​shortcodes/​class-godam-player.php Registers player styles earlier.
inc/​classes/​shortcodes/​class-godam-image.php Preloads layer assets for inline previews.
inc/​classes/​rest-api/​class-meta-rest-fields.php Sanitizes layer data before REST saves.
inc/​classes/​layers/​class-legacy-layer-types.php Preserves legacy Woo layer rendering.
inc/​classes/​layers/​class-core-layer-types.php Loads core types and shared container rendering.
inc/​classes/​class-plugin.php Initializes PHP layer infrastructure.
inc/​classes/​class-elementor-widgets.php Preloads layer assets for Elementor previews.
inc/​classes/​class-blocks.php Loads image-layer preview assets.
inc/​classes/​class-assets.php Derives dependency flags from registrations.
godam.php Loads public PHP Layer API helpers.
assets/​src/​layers/​shared/​overlay.js Connects layer views to shared overlay management.
assets/​src/​layers/​poll/​view.js Registers poll runtime and outcome detection.
assets/​src/​layers/​poll/​poll.php Registers PHP poll rendering.
assets/​src/​layers/​poll/​layer.json Defines poll metadata and defaults.
assets/​src/​layers/​poll/​editor.js Defines poll editor registration.
assets/​src/​layers/​poll/​edit.test.js Updates relocated panel-test imports.
assets/​src/​layers/​poll/​edit.js Relocates the poll settings panel.
assets/​src/​layers/​index.js Registers core editor types.
assets/​src/​layers/​hotspot/​view.js Registers video and image hotspot runtimes.
assets/​src/​layers/​hotspot/​layer.json Defines hotspot metadata and media support.
assets/​src/​layers/​hotspot/​hotspot.php Registers hotspot rendering and image eligibility.
assets/​src/​layers/​hotspot/​editor.js Defines hotspot editor registration.
assets/​src/​layers/​hotspot/​edit.test.js Updates relocated panel-test imports.
assets/​src/​layers/​hotspot/​edit.js Relocates the hotspot settings panel.
assets/​src/​layers/​form/​view.js Registers the provider-aware form runtime.
assets/​src/​layers/​form/​view-providers.js Defines provider availability and submission detection.
assets/​src/​layers/​form/​providers.test.js Tests editor provider registrations.
assets/​src/​layers/​form/​layer.json Defines form metadata and defaults.
assets/​src/​layers/​form/​form.php Registers PHP form rendering and provider variations.
assets/​src/​layers/​form/​editor.js Defines form availability and save validation.
assets/​src/​layers/​form/​edit.test.js Tests provider-panel selection and notices.
assets/​src/​layers/​form/​edit.js Selects registered form-provider panels.
assets/​src/​layers/​cta/​view.js Registers CTA overlay runtime behavior.
assets/​src/​layers/​cta/​layer.json Defines CTA metadata and defaults.
assets/​src/​layers/​cta/​editor.js Defines CTA editor registration.
assets/​src/​layers/​cta/​edit.test.js Updates relocated preview tests.
assets/​src/​layers/​cta/​edit.js Relocates the CTA settings panel.
assets/​src/​layers/​cta/​cta.php Registers HTML and card CTA rendering.
assets/​src/​layers/​ad/​layer.json Defines ad metadata and defaults.
assets/​src/​layers/​ad/​editor.js Defines ad editor registration and availability.
assets/​src/​layers/​ad/​edit.js Relocates the ad settings panel.
assets/​src/​layers/​ad/​ad.php Registers PHP ad-tag support.
assets/​src/​js/​godam-player/​videoPlayer.js Forwards time updates through the runtime host.
assets/​src/​js/​godam-player/​utils/​storage.js Reformats documentation without logic changes.
assets/​src/​js/​godam-player/​utils/​pluginLoader.js Removes type-specific icon detection.
assets/​src/​js/​godam-player/​utils/​layerActions.js Resolves analytics labels from runtime variations.
assets/​src/​js/​godam-player/​utils/​LAYER-REGISTRY-API.md Updates legacy registry API guidance.
assets/​src/​js/​godam-player/​utils/​constants.js Removes hard-coded layer and provider constants.
assets/​src/​js/​godam-player/​managers/​layersManager.test.js Tests runtime-wide layer suppression.
assets/​src/​js/​godam-player/​managers/​layers/​README.md Documents runtime-based manager orchestration.
assets/​src/​js/​godam-player/​managers/​layers/​layerValidator.js Removes centralized type validation.
assets/​src/​js/​godam-player/​managers/​layers/​formLayerManager.test.js Exercises Marketo through runtime mounting.
assets/​src/​js/​godam-player/​layers/​overlay.js Exposes shared overlay lifecycle handlers.
assets/​src/​js/​godam-player/​api/​player.layers.test.js Tests API-created layer lifecycle integration.
assets/​src/​js/​godam-player/​api/​player.js Mounts API-created layers on the runtime host.
assets/​src/​js/​godam-layers/​utils.js Adds defaults, variation, and availability helpers.
assets/​src/​js/​godam-layers/​store.js Stores ordered editor type registrations.
assets/​src/​js/​godam-layers/​runtime/​index.js Initializes the standalone runtime registry.
assets/​src/​js/​godam-layers/​index.js Publishes the editor registry API.
assets/​src/​js/​godam-layers/​deprecated.js Emits legacy API deprecation notices.
assets/​src/​js/​godam-layers/​constants.js Defines registration contracts and defaults.
assets/​src/​blocks/​godam-image/​render.php Filters image layers through PHP registrations.
.eslintrc Recognizes the external editor registry module.
.distignore Excludes layer sources and contributor documentation.

Review effort: Balanced

Comment thread assets/src/layers/form/editor.js Resolved
Comment thread assets/src/layers/form/view.js Resolved
Comment thread assets/src/layers/hotspot/view.js Resolved
KMchaudhary and others added 2 commits November 6, 2026 14:36
develop is at 2.8.0 and 2.7.0 is already released, so the Layer API ships
in 2.8.0. The old add-on hooks are deprecated since 2.8.0 and removed two
minor releases later, in 2.10.0. Updates the PHP and JS notices, the
developer guide and the tests that assert the notice text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Image hotspots drawn twice: when the hotspot view script registers
  after an image frame rendered, the host calls the shared onReady once
  per late layer. onReady now redraws into a fresh wrapper and removes
  the previous one, and destroy() clears it.
- Form layers that couldn't be saved: FormProviderPanel saved the form
  ID under `form_id` when a provider set no idField, but the save check
  only read idField. Both now use getFormIdField().
- The `color` attribute format let extra CSS through, e.g.
  `rgb(0);position:fixed)`. It now uses rtgodam_sanitize_css_color().
- Variation icons: any string was drawn as an <img>, so a Dashicon name
  such as the guide's `icon: 'feedback'` was a broken image. Variations
  now split `icon` / `iconUrl` the way layer types do.

The Jest asset mock now returns a URL-shaped path, as the build does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@subodhr258 subodhr258 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at d1b377c. I read the code: the develop merge, the PHP side, the front-end runtime, and every GoDAM repo that uses the old layer hooks. I did not run it in a browser. CI is green.

The merge resolution is good, and the Woo add-on keeps working through the shims. Before this goes to develop, there are 3 front-end bugs to fix (all of Copilot's findings are real, details in its threads), plus the version strings and one data-loss case on save.

What I checked

Claim How I checked Result
develop's #2246 colour sanitising carried into the render callbacks Compared develop's template diff with Core_Layer_Types::container() ✅ Same: rtgodam_sanitize_css_color(), #FFFFFFB3 default, none for an empty hotspot colour. Brand/appearance colours and transcript_source are kept in the template
Gravity Forms uses rtgodam_get_gravityform_layer_shortcode() class-form-providers.php:173 ✅
#2250 safe links and preview markup kept in the moved panels getSafeLinkUrl / sanitizePreviewMarkup in layers/{cta,hotspot,poll}/edit.js ✅
CI drops the feature/layer-api triggers workflow files ✅
Old hooks keep working behind shims Traced each GoDAM for Woo main call to its shim ✅ All of them: the layer options/components filters, godam_player_render_layer (same args), godamLayerRegistry queue, godamLayerCreators, godamVideoEditorActions proxy
Saved layers keep their shape Layer_Sanitizer ⚠️ Mostly. custom_css is cut on save (inline)
Deprecations say "since 2.8.0, removed in 2.10.0" grep of the head ❌ Still 2.7.0 / 2.9.0 (inline)
PHP 7.4 PHPCompatibilityWP 7.4- on the changed PHP ✅ Clean
Escaping in render callbacks Read every callback ✅

Other repos

  • GoDAM for Woo (main, 2.3.1): works through the shims. It logs console deprecation notices on every player page until rtCamp/godam-for-woo#251 ships.
  • godam-plugin-automation breaks: selectors/godam.js:205-206 use .godam-image-hotspot-group .hotspot and .godam-image-woo-group .hotspot, which this PR removes. The image overlay is now .godam-image-layer-item[data-layer-type="hotspot"|"woo"] (render-image-frame.js:164). The suites image-hotspot.spec.js, image-woo-hotspot.spec.js and woo-hotspot-image-revenue.spec.js will fail. That needs a matching PR there.
  • godam-core, analytics, ai, mcp, upload and the SDKs don't use any of the changed extension points.

Smaller notes (not blocking)

  • godam_player_render_layer no longer fires for ad layers (on develop it fell into the else). I don't know of any consumer.
  • Under WP_DEBUG, do_action_deprecated() runs inside the ob_start() in the registry (:362-372) and the legacy types (:64-67), so the PHP notice is printed inside the layer markup.
  • The PHPCS include warning at class-layer-type-registry.php:803 is safe: it's RTGODAM_PATH plus a literal. Add the same phpcs:ignore used at :627.
  • The 11 part PRs were merged into feature/layer-api without a GitHub approval, so this PR is the first approved review of the whole stack.

Not tested: a live run of the late-script cases, Ads, and Woo hotspots on the front end. The front-end findings below were reproduced in Jest against the PR's code.

- Form save check: a layer whose form provider isn't registered (its
  add-on is inactive) no longer blocks saving the attachment; a layer
  without form_type is checked as the default provider, as PHP reads it.
- Late form scripts: the Form view registers the core providers before
  its runtime, so layers waiting for the runtime pass validate. Layers
  whose variation registers later (an add-on provider) are mounted then,
  through the new whenLayerRuntimeVariation().
- custom_css: saved as written again, as on develop. wp_strip_all_tags()
  cut CSS at any `<` (`@media (width<=600px)`, `content: "<"`); only
  `</style` is removed now.
- An add-on's validate() or usesIconFont() that throws is logged and
  treated as false, so the other layers still mount.
- Variation attributes are compared by value in the editor and runtime,
  so array or object values match saved layers.
- FormProviderPanel doesn't fetch a preview for an unavailable provider.
- The godam_player_render_layer deprecation is reported before output
  buffering, so a WP_DEBUG notice isn't printed into the layer markup.
- phpcs:ignore for the runtime script's asset include.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KMchaudhary

Copy link
Copy Markdown
Collaborator Author

Pushed three commits covering the review feedback:

  • d0fe1a3: deprecations dated 2.8.0, removed in 2.10.0.
  • 0be7823: duplicate image hotspots when the hotspot script loads late, the form ID field for providers without idField, the color attribute format now using rtgodam_sanitize_css_color(), and variation icons (a Dashicon name like 'feedback' is no longer drawn as an <img>).
  • bc88d8a: the inline threads above, plus two items from Copilot's overview. Variation attributes are now compared by value in the editor and the runtime, so array or object values match. FormProviderPanel no longer fetches a preview for an unavailable provider. Also, the godam_player_render_layer deprecation is reported before output buffering, so a WP_DEBUG notice isn't printed into the layer markup.

Not changed:

  • Image hotspots send no "viewed" events, the same as on develop.
  • godam_player_render_layer no longer fires for Ad layers, and no consumer is known.
  • The godam-plugin-automation selectors (.godam-image-hotspot-group, .godam-image-woo-group) need a matching PR in that repo.

Testing: Jest (1,256) and PHPUnit (1,437) pass. Each new test fails on the previous code. I also re-tested every layer type on a local site built from this branch:

  • CTA, the form plugins, the poll, hotspots and the Woo product hotspot on video.
  • A real Contact Form 7 submission, which turned Skip into Continue and recorded a submitted event.
  • The Ad tag and VMAP.
  • Image hotspots and Woo markers.
  • Every editor panel and the Add layer menu, for video and image.
  • A save that left the layers unchanged.

The late-script fixes are covered only by unit tests, because I couldn't delay a script in the browser.

Comment thread assets/src/layers/ad/ad.php Resolved
- Layer_Type_Registry (and REST_API\Jetpack in the form providers) is
  imported with `use` instead of written as a fully qualified name.
- The core layer files (ad, cta, form, hotspot, poll) find their
  layer.json and class-form-providers.php through
  Core_Layer_Types::get_layers_dir(), built on RTGODAM_PATH, instead of
  __DIR__. get_layers_dir() now returns the folder register() is loading
  from, so a type's PHP, layer.json and the view.js it names come from
  the same build or source folder.
- untrailingslashit() stub for the PHPUnit run.

Add-on examples in docs/layer-api.md and layer-functions.php keep
__DIR__, which is right for code that lives in another plugin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@rtBot rtBot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code analysis identified issues

action-phpcs-code-review has identified potential problems in this pull request during automated scanning. We recommend reviewing the issues noted and that they are resolved.

phpcs scanning turned up:

⚠️ 1 warning


Powered by rtCamp's GitHub Actions Library

Comment thread assets/src/layers/form/form.php Resolved

@subodhr258 subodhr258 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed at 08a8401. I checked the four commits since my last review (d0fe1a3, 0be7823, bc88d8a, 08a8401) and ran the tests locally. All six findings from my earlier review are fixed. I replied in each thread with how I checked it. I found nothing new.

What I checked

Item How I checked Result
Deprecations dated 2.8.0, removal in 2.10.0 git grep for 2.7.0 / 2.9.0 in the layer PHP, JS and docs ✅
custom_css no longer cut on save Read strip_style_end(), ran LayerSanitizerTest ✅
Form editor validate with an inactive add-on provider Read form/editor.js:41-44, ran providers.test.js ✅
Late Form view script still mounts the saved forms Read registerFormRuntime(), ran views.test.js and layersManager.test.js ✅
Late hotspot script: no duplicate markers Ran render-image-frame.test.js ✅
An add-on validate() that throws doesn't stop the other layers Ran layersManager.test.js ✅
08a8401: use imports and core layers loaded through Core_Layer_Types::get_layers_dir() Read the diff. Each use matches a real class (REST_API\Jetpack doesn't clash with anything in that file). get_layers_dir() is only called from the core layer PHP, and register() sets it before including that PHP ✅

Tests (local, PHP 8.5):

  • Jest: the layer, player, image-layer and video-editor suites pass, 824 tests in 48 suites.
  • PHPUnit: 1,437 tests run. The 30 errors are all PHP 8.5's setAccessible() deprecation in tests this PR doesn't touch (Elementor gallery, media paths, Marketo, PostHog). The layer, hotspot, form and sanitizer tests pass, 330 of them.
  • CI: green, except Plugin Check, which was still running when I posted.

Still open, not in this PR

  • godam-plugin-automation: the image hotspot selectors (.godam-image-hotspot-group, .godam-image-woo-group) still need a matching PR in that repo. I couldn't find one yet. Without it, the three image hotspot suites will fail once this reaches develop.

Not tested: a live browser run. The late-script fixes are covered by unit tests only, as the author noted.

rtBot flagged WordPressVIPMinimum.Files.IncludingFile.UsingCustomConstant
on the require_once added in 08a8401. The path is the plugin's own
core layer folder (RTGODAM_PATH based) plus a fixed filename.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@subodhr258 subodhr258 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at ece40c9. All findings from my earlier reviews are fixed. The only change since 08a8401 is the phpcs:ignore on the form providers include. CI is green, including Plugin Check.

@KMchaudhary
KMchaudhary merged commit 105e176 into develop Nov 11, 2026
6 checks passed
@KMchaudhary
KMchaudhary deleted the feature/layer-api branch November 11, 2026 09:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants